<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>

<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
	<title>Marvin JS - How to embed it</title>
	<link type="text/css" rel="stylesheet" href="../../css/doc.css" />
	<link type="text/css" rel="stylesheet" href="../../js/lib/rainbow/github.css" />
	<script src="../../js/lib/rainbow/rainbow-custom.min.js"></script>
	<script src="../../js/lib/jquery-1.9.1.min.js"></script>
</head>

<body>
<h1>Marvin JS - How to embed it</h1>
<div style="clear: both; width: 100%; text-align: right;"><a href="../index.html">Back to index</a></div>

<p>Insert an <strong>iframe</strong> into your page and specify its size. It will determine the dimensions of the editor. Load the <strong>editor.html</strong> file into
this frame and define an <code>id</code> that helps to refer to it later. The size of the iframe should be set in exact units 
(e.g. pixels): the minimum values should be 500px * 450px. It's recommended to set its <code>overflow</code> property to <code>hidden</code> and to set a <em>solid</em> border to the iframe element.
</p>
<pre><code data-language="javascript">&lt;iframe id=&quot;sketch&quot; src=&quot;../editor.html&quot; 
	style=&quot;overflow: hidden; min-width: 500px; min-height: 450px; border: 1px solid darkgray;&quot;  /&gt;</code></pre>

<p>If you need default web services but you do not wish setup each one, you can use alternative version of <code>editor.html</code>: <strong>editorws.html</strong>
</p><p>It presets default web services at startup.</p>

<pre><code data-language="javascript">&lt;iframe id=&quot;sketch&quot; src=&quot;../editorws.html&quot; 
	style=&quot;overflow: hidden; min-width: 500px; min-height: 450px; border: 1px solid darkgray;&quot;  /&gt;</code></pre>
<p>Please, note that web services have to be available at the default location that <strong>webservices.js</strong> defines. You can modify the default location in this file 
by overwriting these settings. <em>editorws.html</em> refers to this external JavaScript file when it retrieves the default webservice config.
If you link this file into your code, you can also refer to it by the <strong>getDefaultServices()</strong> function.</p>

<h2>Accessing functions of the sketcher</h2>

<p>There is no guarantee that the editor is already alive when the loading of the parent page (where its iframe is inserted) has been finished.<p>
<p>Because of this, getting the reference to the editor is not trivial.</p>
<p>We provide a helper API to access it. Below, we demonstrate how to use this helper API or how you can access the sketcher without it.
	<ul>
		<li><a href="#embed_with_helper_api">Embed with the helper API</a></li>
		<li><a href="#embed_without_helper_api">Embed without the helper API</a></li>
	</ul>
</p>

<h3><a name="embed_with_helper_api"></a>Embed with the helper API</code></a></h3>
<p>The <strong>marvinjslauncher.js</strong> JavaScript library provides an interface to control the event when the editor is loaded and helps to get a reference to the editor to be
able to refer to the editor API.</p>

<p>First of all, insert the following lines into header of your web page to import it 
(<code>promise-1.0.0.min.js</code> is a dependency of <code>marvinjslauncher.js</code>).</p>
<pre><code data-language="javascript">&lt;script src="gui/lib/promise-1.0.0.min.js"&gt;&lt;/script&gt;
&lt;script src="js/marvinjslauncher.js"&gt;&lt;/script&gt;</code></pre>


<p>The <code>marvinjslauncher.js</code> loads the <strong>MarvinJSUtil</strong> object whose functions are described below. This API operates with
Promise objects. If you are not familiar with the Promise pattern, you can read more about it here:
<a href="http://wiki.commonjs.org/wiki/Promises/A">Promise/A</a></p><p>Not all browsers provide Promise implementation yet. Because of this, we
need the <strong>promise-1.0.0.min.js</strong>, that provides Promise implementation where it is not implemented yet.

<div class="table">
	<!--  header -->
	<div class="api-header">MarvinJSUtil.getEditor(iframeid) <span class="rightSide api-method-returntype">Promise</span></div>
	<!--  body -->
	<div class="api-body">
		<p><strong>Description</strong>
		Returns a dynamically generated Promise object to observer when the sketcher in the given <code>iframe</code> has been successfully loaded or failed.</p>
		<p><strong>Parameters</strong><p>
		<div class="inner-api-table">
				<p><strong>iframeid</strong></p>
				<p>Type: String</p>
				<p>The ID of the iframe that contains the sketcker</p>
		</div>
		<p><strong>Returns</strong></p>
		<div class="inner-api-table">
				<p>A Promise object to access the reference to the loaded sketcher object or get a notification if loading of the sketcher failed.</p>
		</div>
		<h2>Usage</h2>
		<p>Call the <code>then(onFullfiled, onRejected)</code> function of the Promise returned by <code>MarvinJSUtil.getEditor(iframeid)</code> to be able to store
		the reference to the sketcher.</p>
		<pre><code data-language="javascript">var marvinSketcherInstance;
MarvinJSUtil.getEditor("#sketch").then(function(sketcherInstance) {
	marvinSketcherInstance = sketcherInstance;
}, function(error) {
	alert("Loading of the sketcher failed"+error);
});</code></pre>
		
	</div>
</div>	
<div class="table">
	<!--  header -->
	<div class="api-header">MarvinJSUtil.getPackage(iframeid) <span class="rightSide api-method-returntype">Promise</span></div>
	<!--  body -->
	<div class="api-body">
		<p><strong>Description</strong>
		Returns a dynamically generated Promise object to observer when the Marvin JS package is ready to be used in the given <code>iframe</code>.</p>
		<p><strong>Parameters</strong><p>
		<div class="inner-api-table">
				<p><strong>iframeid</strong></p>
				<p>Type: String</p>
				<p>The ID of the iframe that contains the sketcker</p>
		</div>
		<p><strong>Returns</strong></p>
		<div class="inner-api-table">
				<p>A Promise object to access the reference to the object that wraps the Marvin JS API in the given <code>iframe</code> or gets a notification if any error occurs during its loading.</p>
		</div>
		<h2>Usage</h2>
		<p>Call the <code>then(onFullfiled, onRejected)</code> function of the Promise returned by <code>MarvinJSUtil.getEditor(iframeid)</code> to be able to store
		the reference to the sketcher.</p>
		<pre><code data-language="javascript">var marvin;
MarvinJSUtil.getPackage("#sketch").then(function(marvinPackage) {
	marvin = marvinPackage;	
}, function(error) {
	alert("Marvin package is not available:" +error);
});</code></pre>
	</div>
</div>

<h3><a name="embed_without_helper_api"></a>Embed without the helper API</h3>

<p>If you do not use the helper API, accessing of the sketcher is more complicated but not impossible:</p>
<pre><code data-language="javascript">var marvinSketch;

document.getElementById(&quot;sketch&quot;).addEventListener(&quot;load&quot;, function() { // listen when the document in the iframe is loaded

	var eframeWin = document.getElementById(&quot;sketch&quot;).contentWindow;
		if(typeof eframeWin != 'undefined') { // if the contentWindow property of iframe is available, you can access inner content
			try {
				var marvin = eframeWin.marvin; // reference to marvin library in the iframe
				if(marvin != null) {
					marvin.onReady(function() { // onReady is performed when loading of the marvin API is ready (hopefully, sketcher is already instantiated)
						if(typeof marvin.sketch != 'undefined') { // undefined if you have no right to access it or instantiation failed
							marvinSketch = marvin.sketch;
							marvinSketch.importAsMrv(s);
						}
					});
				}
			} catch(e) {
				alert(e);
			}
		}
	});</code></pre> 
<div style="clear: both; width: 100%; text-align: right;"><a href="../index.html">Back to index</a></div>

</body>

</html>
